feat(runtime): expose process lifecycle hooks to embedding hosts by MertBasar0 · Pull Request #514 · openclaw/acpx

MertBasar0 · 2026-08-22T22:25:27Z

Related: #499

What Problem This Solves

Embedding hosts can launch ACP agents through AcpClient or AcpRuntime, but they currently have no supported way to durably record process ownership around the exact spawn boundary. Hosts that need crash recovery or process-lease reconciliation must either wrap ACPX internals or accept a gap between preparing a launch and learning the child PID.

Why This Change Was Made

This adds an optional lifecycle contract with immutable, correlated events for pre-spawn admission, successful spawn, spawn failure, and process exit. Runtime-created clients also receive stable session/probe scopes.

The two admission hooks are deliberately awaited: rejecting before spawn prevents launch, while rejecting after spawn terminates the child before returning the error. Failure and exit observers remain best-effort and cannot mask the underlying process outcome. Exit notification is ordered after spawned admission settles, avoiding a stale-lease race when a child exits quickly.

This is an embedding seam only. It does not add persistence, process-tree cleanup, or host-specific lease policy to ACPX, and therefore does not claim to close #499.

User Impact

Embedding developers can now implement durable host-owned launch tracking without wrapping ACPX spawn internals. Existing clients are unaffected because every lifecycle hook is optional.

Evidence

Full pnpm run check passes in a clean Linux checkout: formatting, TypeScript checks, type-aware lint, package and replay-viewer builds, 942 repository tests, and 130 coverage tests.
Nine focused lifecycle/runtime regression tests pass, covering event ordering, admission rejection, child cleanup, spawn-failure correlation, a never-settling failure observer, early exit during successful spawned admission, initialization exit, runtime-session scope, and probe scope.
The P2 follow-up makes onSpawnFailed nonblocking while preserving synchronous invocation, correlation data, and logging for synchronous throws and asynchronous rejections.
The P1 follow-up installs startup-exit observation before awaited spawned admission and checks already-recorded child exit state, preventing startup from hanging when the agent exits while a successful admission hook is still pending.
Repository autoreview of the P2 follow-up delta completed cleanly: no accepted/actionable findings; overall result “patch is correct” (0.98 confidence).
Repository autoreview of the P1 follow-up delta also completed cleanly: no accepted/actionable findings; overall result “patch is correct” (0.88 confidence).
A real embedding-host run on the current PR head with the published @agentclientprotocol/codex-acp 1.6.2 adapter passes; redacted runtime proof is included below.
Branch is based on the current openclaw/acpx main at commit time.

Real embedding-host proof

Environment: WSL2 Linux x64, Node v24.15.0, PR head 08a8601, published @agentclientprotocol/codex-acp 1.6.2, existing Codex ChatGPT login. No credential values were logged. The temporary external host imported the built public dist/runtime.js API and used createAcpRuntime, createRuntimeStore, and createAgentRegistry; it was not added to the PR.

The first scenario initialized a real ACP session through codex-acp, then closed it. The second used a real Node child that exited with code 17 while a slow but successful onSpawned admission hook was pending. The third used a real OS spawn failure while onSpawnFailed deliberately returned a Promise that never settles.

environment platform=linux arch=x64 node=v24.15.0 head=08a8601 adapter=@agentclientprotocol/codex-acp@1.6.2
before_spawn launch=launch-1 scope=runtime-session:proof-session command=codex-acp cwd=<workspace>
spawned launch=launch-1 scope=runtime-session:proof-session pid=<ephemeral> startedAt=<timestamp>
session_ready sessionKey=proof-session backend=acpx backendSessionIdPresent=true
exit launch=launch-1 scope=runtime-session:proof-session pid=<same-ephemeral> exitCode=null signal=SIGTERM exitedAt=<timestamp>
assertion_pass scenario=real_adapter_lifecycle_current_head order=before_spawn,spawned,exit correlatedLaunch=launch-1
admission_before_spawn launch=launch-2 scope=runtime-session:admission-proof command=node cwd=<workspace>
admission_spawned_start launch=launch-2 scope=runtime-session:admission-proof pid=<ephemeral>
admission_spawned_end launch=launch-2 pid=<same-ephemeral>
admission_exit launch=launch-2 pid=<same-ephemeral> exitCode=17 signal=null
assertion_pass scenario=exit_during_successful_spawned_admission outcome=rejected errorName=AgentStartupError exitCode=17 stderrCaptured=true elapsedMs=104 deadlineMs=2000 order=before_spawn,spawned_start,spawned_end,exit
failure_before_spawn launch=launch-3 scope=runtime-session:failure-proof command=acpx-proof-agent-that-does-not-exist
spawn_failed_observer_entered launch=launch-3 errorName=AgentSpawnError
assertion_pass scenario=nonblocking_never_settling_spawn_failure_observer outcome=rejected errorName=AgentSpawnError observerCalled=true elapsedMs=104 deadlineMs=2000
proof_pass scenarios=real_adapter_lifecycle_current_head,exit_during_successful_spawned_admission,nonblocking_never_settling_spawn_failure_observer

The successful adapter PID and the admission-test PID were both confirmed exited after the run. No model prompt or inference was needed; this proof exercises the embedding boundary, real adapter process lifecycle, ACP session initialization, correlation, the repaired startup-exit path, and the repaired spawn-failure semantics.

AI assistance

The implementation was AI-assisted. I reviewed the resulting lifecycle contract, failure semantics, tests, generated diff, and real embedding-host trace, and validated it with the checks listed above.

clawsweeper · 2026-08-22T22:25:30Z

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

clawsweeper · 2026-08-22T22:35:37Z

Codex review: needs maintainer review before merge. Reviewed August 25, 2026, 6:07 AM ET / 10:07 UTC.

ClawSweeper review

What this changes

Adds optional lifecycle hooks for embedding hosts to observe or admit ACP agent process spawning, failures, and exits with session or probe correlation.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for explicit maintainer approval of a new public runtime contract: the implementation and proof are solid, but awaited host admission hooks intentionally make host callback behavior part of ACP startup availability.

Priority: P2
Reviewed head: 08a86019e73ea140f5eb3e2eebfbc061344eb13e
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Strong real runtime evidence and focused regression coverage support the implementation; the remaining gate is a public API and availability-semantics decision.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body provides redacted after-fix live output from a real embedding host and ACP adapter, including the repaired exit-during-admission and nonblocking failure-observer paths.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body provides redacted after-fix live output from a real embedding host and ACP adapter, including the repaired exit-during-admission and nonblocking failure-observer paths.
Evidence reviewed	6 items	Public lifecycle contract: The branch defines immutable launch, started, failure, and exit event shapes and documents the two admission hooks as startup-aborting boundaries. Runtime propagation and ordering: The client awaits pre-spawn and spawned admission, installs exit observation before spawned admission settles, and forwards the hook and scoped identity through runtime sessions and probes. Regression coverage: Focused tests cover ordered events, rejected admission, cleanup, correlated spawn failure, nonblocking failure observers, and a child exiting during successful spawned admission.
Findings	None	None.
Security	None	None.

Live Verification

Command: pnpm run build

Result: PASS (completed)

pnpm run build
runner@runnervm76f27:/tmp/clawsweeper-live-proof-514-IZDLZy/target$ pnpm run build

› acpx@0.13.1 build /tmp/clawsweeper-live-proof-514-IZDLZy/target
› tsdown src/cli.ts src/flows.ts src/runtime.ts --format esm --dts --clean --platform node --target node22 --no-fixedExtension

ℹ tsdown v0.22.14 powered by rolldown v1.2.0
ℹ config file: /tmp/clawsweeper-live-proof-514-IZDLZy/target/package.json
ℹ entry: src/cli.ts, src/flows.ts, src/runtime.ts
ℹ target: node22
ℹ tsconfig: tsconfig.json
ℹ Build start
pnpm run build
ℹ Granting execute permission to dist/cli.js
ℹ dist/cli.js                             116.67 kB │ gzip:  24.77 kB
ℹ dist/runtime.js                          79.10 kB │ gzip:  17.56 kB
ℹ dist/flows.js                             0.44 kB │ gzip:   0.23 kB
ℹ dist/live-checkpoint-D5RVlQRW.js.map    535.23 kB │ gzip: 112.60 kB
ℹ dist/output-BY8OZEWF.js.map             363.47 kB │ gzip:  73.91 kB
ℹ dist/live-checkpoint-D5RVlQRW.js        250.03 kB │ gzip:  55.18 kB
ℹ dist/cli.js.map                         232.85 kB │ gzip:  47.97 kB
ℹ dist/output-BY8OZEWF.js                 169.25 kB │ gzip:  36.25 kB
ℹ dist/runtime.js.map                     164.86 kB │ gzip:  35.24 kB
ℹ dist/flows-CjBcuuLC.js.map              143.48 kB │ gzip:  31.10 kB
ℹ dist/flows-CjBcuuLC.js                   68.15 kB │ gzip:  15.54 kB
ℹ dist/flags-Dx8qNx2h.js.map               30.63 kB │ gzip:   7.71 kB
ℹ dist/cli-DFfHshkH.js.map                 16.09 kB │ gzip:   4.55 kB
ℹ dist/flags-Dx8qNx2h.js                   15.63 kB │ gzip:   4.16 kB
ℹ dist/cli-DFfHshkH.js                      8.43 kB │ gzip:   2.59 kB
ℹ dist/runtime.d.ts.map                     3.71 kB │ gzip:   1.31 kB
ℹ dist/flows.d.ts.map                       2.65 kB │ gzip:   0.88 kB
ℹ dist/session-options-Cu0jtiOV.d.ts.map    2.24 kB │ gzip:   0.81 kB
ℹ dist/client-Ozy3hbaj.d.ts.map             1.76 kB │ gzip:   0.76 kB
ℹ dist/cli.d.ts.map                         0.21 kB │ gzip:   0.18 kB
ℹ dist/runtime.d.ts                        21.18 kB │ gzip:   5.56 kB
ℹ dist/flows.d.ts                          10.70 kB │ gzip:   2.56 kB
ℹ dist/cli.d.ts                             0.72 kB │ gzip:   0.34 kB
ℹ dist/session-options-Cu0jtiOV.d.ts       10.82 kB │ gzip:   3.26 kB
ℹ dist/client-Ozy3hbaj.d.ts                 8.65 kB │ gzip:   2.42 kB
ℹ 25 files, total: 2.26 MB
[INEFFECTIVE_DYNAMIC_IMPORT] src/cli/output/render.ts is dynamically imported by src/cli/command-handlers.ts but also statically imported by src/cli-core.ts, sr
c/cli/status-command.ts, dynamic import will not move module into another chunk.

✔ Build complete in 2167ms
runner@runnervm76f27:/tmp/clawsweeper-live-proof-514-IZDLZy/target$ pnpm run build
node --input-type=module -e "import('./dist/runtime.js').then((runtime) =› console.log(typeof runtime.createAcpRuntime))"

› acpx@0.13.1 build /tmp/clawsweeper-live-proof-514-IZDLZy/target
› tsdown src/cli.ts src/flows.ts src/runtime.ts --format esm --dts --clean --platform node --target node22 --no-fixedExtension

ℹ tsdown v0.22.14 powered by rolldown v1.2.0
ℹ config file: /tmp/clawsweeper-live-proof-514-IZDLZy/target/package.json
ℹ entry: src/cli.ts, src/flows.ts, src/runtime.ts
ℹ target: node22
ℹ tsconfig: tsconfig.json
ℹ Build start
ℹ Cleaning 25 files
ℹ Granting execute permission to dist/cli.js
ℹ dist/cli.js                             116.67 kB │ gzip:  24.77 kB
ℹ dist/runtime.js                          79.10 kB │ gzip:  17.56 kB
ℹ dist/flows.js                             0.44 kB │ gzip:   0.23 kB
ℹ dist/live-checkpoint-D5RVlQRW.js.map    535.23 kB │ gzip: 112.60 kB
ℹ dist/output-BY8OZEWF.js.map             363.47 kB │ gzip:  73.91 kB
ℹ dist/live-checkpoint-D5RVlQRW.js        250.03 kB │ gzip:  55.18 kB
ℹ dist/cli.js.map                         232.85 kB │ gzip:  47.97 kB
ℹ dist/output-BY8OZEWF.js                 169.25 kB │ gzip:  36.25 kB
ℹ dist/runtime.js.map                     164.86 kB │ gzip:  35.24 kB
ℹ dist/flows-CjBcuuLC.js.map 
… output truncated …

Assertions:

PASS expect_output: function

How this fits together

Embedding hosts use the runtime API to create ACP clients and sessions, which launch an external ACP agent process. This change exposes the launch boundary to the host before startup and reports its eventual failure or exit.

flowchart LR
  A[Embedding host] --> B[ACP runtime]
  B --> C[Lifecycle-aware client startup]
  C --> D[Admission hooks]
  D --> E[ACP agent process]
  E --> F[ACP session initialization]
  E --> G[Failure and exit observation]

Decision needed

Question	Recommendation
Should awaited pre-spawn and post-spawn lifecycle admission become a permanent public ACP runtime contract, with embedding hosts responsible for timeout and recovery behavior?	Adopt the admission contract: Accept awaited lifecycle admission as an opt-in host responsibility and merge the documented ordering and cleanup semantics.

Why: VISION.md treats public conventions as durable API surface; this optional hook is intentionally small and backend-oriented, but its ordering and failure semantics cannot safely be chosen by automated review.

Before merge

Resolve merge risk (P2) - Awaited onBeforeSpawn and onSpawned callbacks deliberately make an embedding host's persistence latency, timeout policy, and failure handling part of agent startup availability.
Complete next step (P2) - A maintainer must decide the durable public ordering, failure, and timeout responsibility for awaited lifecycle admission before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and regression coverage	production +260, tests +297, changelog +2	The new public runtime seam is accompanied by focused coverage of its critical ordering and failure paths.

Merge-risk options

Maintainer options:

Adopt bounded host responsibility (recommended)
Approve the awaited admission design with the explicit expectation that embedding hosts provide their own timeout and recovery policy.
Define a bounded alternative
Require a timeout, cancellation, or nonblocking lifecycle design before making the hook contract public.
Pause the API addition
Defer the new lifecycle surface until maintainers choose a durable public contract.

Technical review

Best possible solution:

Land the narrow lifecycle seam only if maintainers want host-owned admission to be a stable runtime API and explicitly accept that hosts own its timeout and recovery policy.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a new API surface, and the PR supplies a real embedding-host trace for the proposed behavior.

Is this the best way to solve the issue?

Unclear: the small host-owned seam fits the backend direction, but maintainers must choose whether its awaited admission behavior is the permanent API contract.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d4c16ab32154.

Labels

Label justifications:

P2: This is a bounded embedding-runtime feature whose availability semantics need normal-priority maintainer review.
merge-risk: 🚨 availability: Opt-in admission hooks can intentionally delay or prevent startup when host callbacks stall or fail.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body provides redacted after-fix live output from a real embedding host and ACP adapter, including the repaired exit-during-admission and nonblocking failure-observer paths.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides redacted after-fix live output from a real embedding host and ACP adapter, including the repaired exit-during-admission and nonblocking failure-observer paths.

Evidence

What I checked:

Public lifecycle contract: The branch defines immutable launch, started, failure, and exit event shapes and documents the two admission hooks as startup-aborting boundaries. (src/types.ts:234, 08a86019e73e)
Runtime propagation and ordering: The client awaits pre-spawn and spawned admission, installs exit observation before spawned admission settles, and forwards the hook and scoped identity through runtime sessions and probes. (src/acp/client.ts:943, 08a86019e73e)
Regression coverage: Focused tests cover ordered events, rejected admission, cleanup, correlated spawn failure, nonblocking failure observers, and a child exiting during successful spawned admission. (test/client.test.ts:1421, 08a86019e73e)
Current-main check: Current main is d4c16ab and its runtime types contain no AcpProcess or processLifecycle surface; its only post-release commit is a dependency refresh, so the requested API is not already implemented there. (src/types.ts:234, d4c16ab32154)
Feature provenance: Runtime embedding support appears to originate with the runtime embedding API commit, while subsequent runtime work added host-facing extension seams and session metadata. (src/runtime/engine/manager.ts:894, be510ba918d4)
Real behavior proof: The PR body includes a redacted current-head embedding-host trace using a real ACP adapter, covering session initialization, exit during admission, and a non-settling spawn-failure observer. (08a86019e73e)

Likely related people:

Onur Solmaz: Introduced the runtime embedding API that owns the public embedding boundary extended by this PR. (role: introduced runtime embedding API; confidence: high; commits: be510ba918d4, a983e63abfa9; files: src/runtime/engine/manager.ts, src/runtime/public/contract.ts)
Dani Akash: Added prior host-facing runtime options and runtime metadata on the same public contract surface. (role: recent runtime API contributor; confidence: medium; commits: f6de6dd18aae, 6a609164fc37; files: src/runtime/engine/manager.ts, src/runtime/public/contract.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

Obtain explicit maintainer approval for the awaited admission and host-timeout contract.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (7 earlier review cycles)

reviewed 2026-08-22T22:28:35.937Z sha 6c6ac17 :: needs real behavior proof before merge. :: [P2] Do not await the best-effort spawn-failure observer
reviewed 2026-08-23T00:04:54.938Z sha a05817a :: needs changes before merge. :: [P1] Register startup exit observation before awaiting admission
reviewed 2026-08-23T15:08:32.876Z sha 08a8601 :: needs real behavior proof before merge. :: none
reviewed 2026-08-23T15:22:11.222Z sha 08a8601 :: needs maintainer review before merge. :: none
reviewed 2026-08-23T15:44:03.186Z sha 08a8601 :: needs maintainer review before merge. :: none
reviewed 2026-08-24T13:50:48.211Z sha 08a8601 :: needs maintainer review before merge. :: none
reviewed 2026-08-24T22:07:28.039Z sha 08a8601 :: needs maintainer review before merge. :: none

MertBasar0 · 2026-08-23T15:06:10Z

@clawsweeper re-review

clawsweeper · 2026-08-23T15:06:16Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

State: Complete
Detail: The durable review result and its route handoff completed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/32648775026
Updated: 2026-08-23T15:30:57.986Z

MertBasar0 · 2026-08-25T19:29:24Z

@steipete This is ready for a maintainer product/API decision. The current head includes real embedding-host proof, all repository checks pass, and ClawSweeper reports no actionable findings.

Could you confirm whether ACPX should adopt the opt-in awaited onBeforeSpawn / onSpawned admission hooks as a public runtime contract, with timeout and recovery policy owned by embedding hosts?

If so, the PR is ready as-is. If you prefer bounded timeout/cancellation or nonblocking semantics, I’m happy to adjust.

feat(runtime): expose process lifecycle hooks

6c6ac17

MertBasar0 mentioned this pull request Aug 22, 2026

ACPX direct-agent launches lack durable process-lease coverage without upstream lifecycle hooks openclaw/openclaw#128006

Closed

fix(runtime): keep spawn failure observers nonblocking

a05817a

fix(runtime): observe exits during spawned admission

08a8601

MertBasar0 marked this pull request as ready for review August 23, 2026 15:41

MertBasar0 requested a review from a team as a code owner August 23, 2026 15:41

Navigation Menu

Uh oh!

feat(runtime): expose process lifecycle hooks to embedding hosts - #514

feat(runtime): expose process lifecycle hooks to embedding hosts#514
MertBasar0 wants to merge 3 commits into
openclaw:mainfrom
MertBasar0:feat/process-lifecycle-hooks

MertBasar0 commented Aug 22, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Aug 22, 2026

Uh oh!

clawsweeper Bot commented Aug 22, 2026 •

edited

Loading

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Uh oh!

MertBasar0 commented Aug 23, 2026

Uh oh!

clawsweeper Bot commented Aug 23, 2026 •

edited

Loading

Uh oh!

MertBasar0 commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

MertBasar0 commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Real embedding-host proof

AI assistance

Uh oh!

clawsweeper Bot commented Aug 22, 2026

Uh oh!

clawsweeper Bot commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ClawSweeper review

What this changes

Merge readiness

Review scores

Verification

Live Verification

How this fits together

Decision needed

Before merge

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Uh oh!

MertBasar0 commented Aug 23, 2026

Uh oh!

clawsweeper Bot commented Aug 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MertBasar0 commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

MertBasar0 commented Aug 22, 2026 •

edited

Loading

clawsweeper Bot commented Aug 22, 2026 •

edited

Loading

clawsweeper Bot commented Aug 23, 2026 •

edited

Loading